3D GFX/3D GFX.iso/amiutils/i_l/jacosub/documentation/arexx.doc

Text File | 1995-12-30 | 7KB | 200 lines

JACOsub ARexx Communications
============================


EXECUTING AREXX SCRIPTS FROM JACOSUB
====================================

You can execute ARexx scripts at specific times in JACOsub scripts while
the JACOsub script is playing.  Simply use the RX directive in a timed
line.  The format of such a line in a JACOsub script is:

<start time> <end time> RX <ARexx script name to execute>

<end time> is ignored, but should be slightly greater than the start time
to avoid a compiler warning.  See the RX directive in the file JScripts.doc
for more information.


COMMUNICATING WITH JACOSUB THROUGH AREXX
========================================

JACOsub's ARexx port is called 'JACOsub' (note the capitalization).  The
program accepts several different commands through its ARexx port.  They
are described below, grouped into the categories of file commands, script
play commands, and editor commands.  Examples of usage for file commands
and script play commands may be found in the rexx subdirectory.


ARexx file commands
-------------------

'LOADSCRIPT' FILENAME/A

   Load a script called FILENAME into memory.  FILENAME should end with an
   appropriate script extension (such as ".js").  RESULT is returned as
   0=success, 1=failure.

'SAVESCRIPT' FILENAME/A

   Write the script currently in memory to a file using the name FILENAME.
   RESULT is returned as 0=success, 1=failure.

'QUIT'

   Terminate JACOsub, remove from memory.  No return value.


ARexx script play commands
--------------------------

'BEGINTIME' TIME/A UNITS/N

   Set the begin time for playing a script.  TIME is a string such as
   "0:04:35.18", UNITS are optional units per second, describing the
   numbers behind the decimal point in TIME (default UNITS is whatever is
   current in JACOsub).  RESULT is returned as 0=success, 1=bad TIME
   format, or 2=TIME decimal fraction conflicted with UNITS.

'NEXTVIEW'

   To be called after PLAYSTART, but only if PLAYSETUP was called with the
   argument AREXXTRIGGER.  This command causes the play screen to switch to
   the next view.

'PLAYSETUP' [TRIGGER/A]

   Set up program for playing a script.  Script will be compiled if needed.
   RESULT is returned as 0=ready to begin playing, 1=failure.

   The optional argument TRIGGER defaults to the value INTERNAL, which is
   normal play using the internal clock.  The internal run will run either
   polled or as an event generator, according to the Playing/Video config
   setting.

   If TRIGGER is set to AREXX, then JACOsub will expect to receive
   'NEXTVIEW' commands for triggering each switch to the next screenful of
   titles.  This is sort of like the manual step-play mode, only via ARexx.
   It is important to know that short duration blank screens in between
   titles also count as screens that must be triggered.

   If TRIGGER is set to EXTERNCLOCK, then JACOsub will expect to receive
   timer data from a timecode reader.  THIS FEATURE IS NOT YET IMPLEMENTED.
   For now, this setting behaves the same as INTERNAL.

   Any triggering mode will still accept the ESC keystroke to abort play.

'PLAYSTART'

   Start the script playing.  This command should be sent *only* after
   successful execution of PLAYSETUP.  RESULT is returned as 0=success,
   1=failure.

'ABORTPLAY'

   Stop the script play, close play screen.  This command has no effect if
   no script is currently playing.  There is no return value.

'SCREENTOBACK'

  If the play screen exists, hide it behind the Workbench.  There is no
  return value.

'SCREENTOFRONT'

  Make sure the play screen is completely visible (if it exists).  There is
  no return value.


ARexx editor commands
---------------------

JACOsub maintains a "current line" pointer for ARexx.  The initial value is
the top line of the script.  The WHICHLINE argument in these commands
specifies on which line the command should operate.  The allowed values
that may be passed for WHICHLINE are:

   CURRENT       Current line.  The current line pointer is not changed.
   NEXT          Next line.  Command will fail with RESULT=1 if there
                 is no next line, otherwise the current line pointer is
                 changed to the next line.
   TOP           Top line.  Current line pointer is changed to the top.
   line number   Row in the editor.  Command will fail with RESULT=1 if the
                 line does not exist in the script, otherwise the current
                 line pointer is changed to the specified line.

All editor commands return RESULT as 0=success, 1=failure.  An editor
command may fail for two reasons: specified line does not exist, or memory
could not be allocated.  In any case, here are the commands:


'APPENDLINE' TEXT/A

   Append a line containing TEXT to the end of the script.  The current
   line pointer is updated to point to this new line.

'DELETELINE' WHICHLINE/A

   Delete the specified line.  The current line pointer is advanced to the
   line that follows the one to be deleted, if it was deleted successfully.

'GETLINE' WHICHLINE/A

   This command copies the specified line into a variable called JSTEXT and
   returns it as a result, in addition to the RESULT code.

'GETROW'

   The current line number is returned in RESULT.

'INSERTLINE' WHICHLINE/A TEXT/A

   Insert a line containing TEXT in front of the specified line.

'REPLACELINE' WHICHLINE/A TEXT/A

   Replace the specified line with a line containing TEXT.

'SETCURRENTLINE' WHICHLINE/A

   Move the current line pointer to the specified line.  You will probably
   not have to use this command, because the others also contain a current
   line setting.


CONTROLLING THE GVP G-LOCK OR THE NEWTEK VIDEO TOASTER
======================================================

Unlike the SuperGen, which JACOsub can control directly, performing
dissolves with the GVP genlock and the Toaster genlock must be done through
ARexx.  If you have configured JACOsub so that the GENLOCK setting is GVP
or TOASTER, then JACOsub will look for a script called gvpfade.jsrx (for
the GVP) or toasterfade.jsrx (for the Toaster) and copy it to
ram:glfade.jsrx for faster execution at the appropriate times.  The
original ARexx script should be located in JACOsub's rexx subdirectory, or
the current directory, or in the rexx: directory.

This script is currently not provided.  If you want to write your own
gvpfade.jsrx script, here are the specifications.

<scriptname>.jsrx BVAL/N BTIME/N GVAL/N GTIME/N

where
   <scriptname> can be gvpfade or toasterfade.
   BVAL  is the background video intensity value at which the dissolve
         should finish.  This actually represents "blackness."  Minimum
         value is 0 for full video, maximum is 100 for full black.
         JACOsub assumes the genlock's BVAL=0 at the start of script play.
   BTIME is the length of the background dissolve in field counts (there
         are 60 fields per second in NTSC video).  A value of -1 means to
         ignore the BVAL setting.
   GVAL  is the foreground graphic overlay intensity at which the dissolve
         should finish.  Minimum value is 0 (completely transparent),
         maximum value is 63 (completely opaque).
         JACOsub assumes the genlock's GVAL=100 at the start of script play.
   GTIME is the length of the graphic overlay dissolve in frame counts.  A
         value of -1 means to ignore the GVAL setting.


End of ARexx.doc.